ODDocument

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODDocument

Superclasses
ODRefCntObject --> ODObject
Subclasses
none

An object of the ODDocument class is used to represent a document and manipulate its drafts.

Description
The ODDocument class is implemented differently for different platforms and storage mechanisms.
The set of related classes, ODContainer (page 98), ODDocument, ODDraft (page 147), and ODStorageUnit (page 664) is called a container suite. Container suite classes are implemented as an integrated set for each platform and storage mechanism because they work intimately with one another at many levels. The container suite used by default on the Mac OS platform is the Bento container suite.
An OpenDoc container can contain one or more documents. Each document, in turn, can contain one or more drafts, and each draft can contain one or more storage units. Each container, document, draft, and storage unit has a unique ID.
The document shell or container application creates or accesses a document object by calling the AcquireDocument method (page 100) of the appropriate container. You can obtain a reference to the document's container by calling its GetContainer method (page 142). Each document object has a unique name within its container. The GetName (page 143) and SetName (page 145) methods retrieve and set this name.
Because each draft corresponds to a version of its document, a document can be defined as a collection of versioned drafts. The document shell or container application creates or accesses drafts by calling the document's CreateDraft (page 139), AcquireDraft (page 136), and AcquireBaseDraft (page 134) methods. Other ODDocument methods copy drafts between documents and discard unwanted drafts. ODDocument is responsible for ensuring that there is only one draft object for each draft in a document.
Each draft has permissions that control access to it. Drafts are created with exclusive read/write permissions. The document shell or container application can change a draft's permissions when it calls the document's AcquireDraft and AcquireBaseDraft methods. Access to a draft is guaranteed to be exclusive only if the draft has exclusive read/write permissions.
Drafts are linearly derived in a document. The drafts of a document can be thought of as a stack; the oldest draft, called the base draft, is at the bottom of the stack and the most recent is at the top. A given draft is said to be above an earlier draft and below a more recent draft. The stack of drafts in the document is called the document's draft history. Although part editors can access any draft of a document, only the most recent (topmost) draft can be modified; all earlier drafts are read only.
For more information on how ODDocument and other container-suite classes are used, see the chapters on storage and OpenDoc runtime features in the OpenDoc Programmer's Guide for the MacOS.

Note
Parts are rarely involved with the manipulation of drafts in a document. OpenDoc and the user cooperate to create and manipulate drafts.

Methods
This section presents summary descriptions of the ODDocument methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [D] are typically called by the document shell or container applications.
Draft Creation

CreateDraft [D]
Creates a new most recent draft object in this document.
Exists
Returns a Boolean value that indicates whether the specified draft exists in this document.
Draft Retrieval and Manipulation

CollapseDrafts [D]
Removes the specified range of empty drafts from this document.
AcquireBaseDraft [D]
Returns a reference to the base draft of this document with its permissions set as specified.
AcquireDraft [D]
Returns a reference to the specified draft of this document with its permissions set as specified.
SaveToAPrevDraft [D]
Consolidates the changes in the specified range of drafts.
SetBaseDraftFromForeignDraft [D]
Copies a draft from another document to the base draft of this document.
GetContainer
Returns a reference to the container object that created this document.
GetID
Returns the unique ID of this document.
GetName
Returns the name of this document.
Naming

SetName [D]
Sets the name of this document.

Methods
AcquireBaseDraft
AcquireDraft
CollapseDrafts
CreateDraft
Exists
GetContainer
GetID
GetName
SaveToAPrevDraft
SetBaseDraftFromForeignDraft
SetName